Resource Library: Multimedia/Resource Library: Multimedia.iso/hypertxt/msdos/ebk/eb.doc

Text File | 1991-07-31 | 15KB | 406 lines

     EB HyperText
     ============


     EB, the Electronic Book, is a simple topic oriented
     hypertext viewing program.  Topics may contain links to
     other topics or programs.  A topic may even reside in
     another hypertext file.  The links appear as highlighted
     hot-spots which when activated by the viewer force a jump to
     the specified target topic or program.  The viewer can of
     course backtrack over any jump, a process known as popping
     the hyperstack.  Traditionally all literature has had a
     linear presentation scheme determined by the author.
     Hypertext has liberated the audience by allowing each to
     choose somewhat the order of presentation and the admission
     or omission of material.  Hypertext pundits however have
     largely ignored the qualities of a book that allow its
     reader nonlinear access, namely the Table of Contents and
     Index.  EB incorporates both, hence the name Electronic
     Book.




     EB Hypertext Viewing
     ====================


     Usage:    eb   -m  -ttopic  pathname


    m        optionally force monochrome display
    ttopic        optional topic in hypertext file
    pathname    optional hypertext file


     The following commands are available:


    F1            Help
    F3            Load new HyperText file
    F10, AltT        Table of Contents
    AltF10, AltI        Index
    CR            Tranverse HyperLink
    AltF1, BACKSP        Backtrack HyperLink
    F6            Toggle 25 - 43/50 lines
    ShiftF6            Toggle monochrome/color
    AltX            Exit

         UpArr            Line up
    DnArr            Line down
    LArr            Character left
    RArr            Character right
    CtrlLArr        Word left
    CtrlRArr        Word right
    PgUp            Page up
    PgDn            Page down
    CtrlW            Scroll up
    CtrlZ            Scroll down
    CtrlPgUp        First page of current topic
    CtrlPgDn        Last page of current topic
    Home            Beginning of line
    End            End of line
    CtrlHome        Top of window
    CtrlEnd            Bottom of window

    Tab            Next hyperlink
    ShiftTab        Previous hyperlink


    Typing characters will take you to the first hyperlink
    that matches the prefix thus far typed.  Typing any
    non-matching characters truncates the prefix to begin
    anew the process with the next character typed.



     EB HyperText Authoring
     ======================


     The EB hypertext system is designed to allow hypertext
     authoring with any ASCII editor and the rapid conversion of
     existing material to hypertext.  Taking any existing text
     file you can embed topic/clue specifiers from which EB can
     automatically create a table of contents and index on reader
     demand.  You can also embed hyperlink specifiers.
     Hyperlinks are highlighted text hot-spots that force jumps
     to other topics in any hypertext file or launch programs
     when choosen by your readers.  When the modified text file
     is subsequently viewed with EB, the specifiers are invisible
     to the reader.  Instead the reader is left with hypertext,
     and the ability to instantly jump to the table of contents
     or index and subsequent topic, or across any hyperlink.

     Let's first see how to embed a new topic along with optional
     clues in your text.

         >|topic|clue|clue|<

     The ">|" characters must appear at the start of a new line
     and the specifier must not extend pass the end of the line.
     Specifier lines are limited to 256 characters including the
     new line character.  "Topic" is what ever text you want to
     appear in the table of contents.  Topics appear in the table
     of contents in the same sequential order that they appear in
     the file.  "Clue" is what ever text you want to appear in
     the index.   The index is comprised of an alphabetical
     listing of topics and clues.  From the table of contents or
     index, the reader can instantly jump to the entry's
     corresponding topic.  You can supply as many clues as you
     want or none at all.  Each new clue is introduced with the
     "|" character.  The "|<" characters terminate the topic/clue
     specifier.  The topic begins on the next line after the "|<"
     characters.  The topic/clue specifier is formally called the
     inlinks specifier.

     Each hyperlink is specified in two parts, a launch and a
     target.  The launch is the highlighted text hot-spot in your
     original text and is delimited with the tilde diacritical
     mark.  A corresponding target must appear in the outlinks
     specifier.  Suppose you want the word "time" as in:

        Now is the time for all good authors ...

     is to be a launch.  Simply bracket the word "time" with the
     tilde diacritical mark:

        Now is the ~time~ for all good authors ...

     The first tilde turns on highlighting while the second turns
     it off.  The tildes are invisible when viewed with EB.  This
     implementation of the launch allows the hypertext to appear
     in nearly the same spatial layout when authoring as when
     viewing.  More than one launch may appear on the same line
     but none may wrap to the next line.  Place two tildes
     immediately adjacent to each other if you want a tilde to
     appear as visible text instead of indicating the beginning
     or end of a launch.  Extending our example alittle:

         >|Authoring|<

    Now is the ~time~ for all good authors ...

    <|DOS|>

     The inlinks specifier indicates the start of a new topic
     called "Authoring."  No clues have been specified.  The
     context of this topic includes the one launch indicating
     that the word "time" is to be highlighted.  The outlinks
     specifier terminates the topic and contains the target,
     "DOS",  which the reader will be taken to if the "time"
     hyperlink is choosen.   The outlinks specifier must also
     appear at the start of a new line and not extend beyond the
     end of the line.

     Let's extend our example again:

        >|Authoring|<

    Now is the ~time~ for all good authors to turn their
    ordinary text into ~hypertext!~

    <|DOS|hyped text|>

     A second launch and corresponding target has been added,
     namely "hypertext!" and its target "hyped text".



     Now for the whole example:


        >|Authoring|<

    Now is the ~time~ for all good authors to turn their
    ordinary text into ~hypertext!~

    <|DOS|hyped text|>

    >|Hyped Text|<

    Hyped text is ordinary text with embedded hypertext
    specifiers.

    <||>


    >|DOS|<

     Set DOS

            ~time~        ~date~

    ~Other DOS Commands~

    <|^?command.com /ctime|^>date|^dos.htx|>


     In this example there are three topics: "Authoring", "Hyped
     Text", and "DOS".  Nameless topics are will be unreachable
     if more one such topic exists in the file.  Nameless clues
     serve to other purpose than putting more than one entry into
     the index for a given topic.  "Authoring" is the default
     topic for the file since it appears first.  The "Hyped Text"
     topic doesn't have any hyperlinks.  Notice that the target
     pairing of "hyped text" with the topic "Hyped Text" is case
     insensitive!  The "DOS" topic has three launches all with
     far targets.  The first target is an spawn call to the DOS
     command processor.  The second target demonstrates the
     preferred way to make a system call.  The last target is the
     default (first) topic in the hypertext file entitled
     "dos.htx".  Spawn calls return immediately upon termination
     to the page that spawned them.  System calls ask the user to
     "Press any key ..." before returning.  Besure to read the
     format reference section for complete details!




     EB HyperText Grammar
     ====================


     The production rules below outline the grammar recognized by
     the Electronic Book.  Explanations of the rules follow
     immediately after.  Applying the production rules you can
     construct the format schema of any hypertext file readible
     by EB.  The name of the rule appears to the left and its
     production to the right.  If the production contains rules
     these rules must likewise be expanded until all rules are
     replace with terminal symbols.  Rule names are capitalized
     while terminals begin with lower case.

     For example, starting with "HyperFile", expanding the rule
     provides for a file of optional comments followed by one or
     more "HyperTopics" which may be separated by additional
     comments.  Optional components of the production are
     enclosed in brackets, i.e. [].  Items considered together
     are enclosed in braces, i.e. {}.  The "+" means one or more
     while the "*" means zero or more.  The "|" symbol means
     either that which preceeds or that which follows but not
     both.  If any of these special symbols are preceeded by a
     "\" then it is to be taken literally thus devoid of any
     special meaning.  It's really not as hard as it may seem at
     first glance.  Try your hand at reading the rules and their
     explanations.  It will be easier to understand if you read
     the section on authoring first.


     HyperFile:        [comments]{HyperTopic[comments]}+

     HyperTopic:    Inlinks Context Outlinks

     Inlinks:        >\|topic{\|clue}*\|<

     Context:        [text]{Launch[text]}*

     Outlinks:        <\|[Target{\|Target}*]\|>

     Launch:        ~any text~

     Target:        Near Target | Far Target

     Near Target:    topic  |
                 default

     Far Target:    topic^HyperFileName  |
                 default^HyperFileName |
                 ignore^>system call   |
            ignore^?spawn call

     HyperFileName:    pathname.ext  |
                 pathname      |
            pathname.



     A HyperFile contains one or more HyperTopics.  Any text not
     residing within a HyperTopic is considered a comment and is
     not visible to the reader.

     A HyperTopic is comprised of an inlinks specifier, context
     of the topic, and outlinks specifier.  Only the context is
     visible to the reader.

     An Inlinks specifier contains topic and clue strings which
     must not contain the '|', '>', or '<' characters.
     Furthermore the topic string may not contain the "^"
     character.  One or more clues are optional.  Only the first
     nameless topic in a file will be reachable from the Table of
     Contents, Index, or via a hyper-jump.  Nameless clues serve
     no other purpose than creating more than one entry in the
     Index for a given topic.

     The Context contains all visible text for the topic and any
     number of hyperlink launches.

     An Outlinks specifier contains any number of targets for the
     launches within the Context.  The first target corresponds to
     the first launch, the second target to the second launch,
     and so on.  If a launch doesn't have a corresponding target,
     then the launch is aborted if attempted.  The target strings
     must not contain the '|', '>', or '<' characters.

     A Launch is delimited with the tilde diacritical mark, i.e.
     ~.  The offset text will appear highlighted.  Choosing the
     launch takes the reader to the target, if successful
     otherwise the launch is aborted.  Two tildes appearing
     together in the text will appear as one visible tilde to the
     reader and will not be interpretted as a launch delimiter.

     A Target can be either near or far.

     A Near target specifies a topic within the current hypertext
     file.  The empty string indicates the default topic which is
     considered always to be the first topic of a hypertext file.

     A Far Target specifies either a (default) topic in another
     specified hypertext file or an operating system/spawn call,
     in which case any topic string is simply ignored.

     The HyperFileName is any legal pathname.  When the file
     extension is absent it is assume to be ".htx".  No extension
     can be specified by appending a period to the pathname.

     Notes: In this first version of EB a restriction has been
     placed on the both inlinks and outlinks specifiers to begin
     at the start of a new line and not extend pass the end of
     that line.  The format specification above doesn't require
     this - it is simply to make the parsing of the file faster
     and easier this first time around.  Likewise, launches are
     required to appear on one line and lines are limited to 256
     characters.  The grammar specification has been deliberately
     designed to facilitate the adding of screen formating
     information and application language capabilities, e.g.
     variables, logic flow and I/O masks (both user and file
     interface).



     EB HyperText Registration
     =========================


     EB is meant to be primarily a demonstration of how easy it
     is to use the FlexList programming tool.  EB source code is
     included with FlexList.  Those portions not tightly coupled
     to FlexList are also available as Freeware.  EB was coded
     entirely without cutting any linked list code, FlexList did
     it all.  This version of EB.EXE is freeware, meaning that
     there is no fee for using EB.EXE, but you must leave my
     copyright notice intact!  Shareware/Freeware distributors
     are also free to distribute it.  Commercial venders may
     bundle EB.EXE (unmodified) with their software without cost
     but in any literature mentioning it they must give proper
     credit to PSW!  Licensing is required for other uses, e.g.
     you must register FlexList to incorporate components of EB
     into your software.


     FlexList II ANSI && K&R C            $79.95
     FlexList II C++                $79.95

    * Ready-to-run C/C++ linked lists.
    * Hybrid structure: stack, queue, list, array.
    * Stores Heterogeneous/homogeneous data.
    * Accessible by value, reference or node.
    * Source is also broken in separate files along
        with makefile for easy library building.
    * 100+ page manual


     FlexList is also available at a discount from:

         The Austin Code Works
    11100 Leafwood Lane
    Austin, Texas 78750-3587 USA

    Voice:  [phone]
    FAX:    [phone]
    E-mail: [e-mail]



     Thanks again for taking a look at EB and how easy it is to
     use FlexList in building applications!  I hope you can use
     it in your shareware/commercial efforts to supply hypertext
     manuals to your customers.  Your comments, suggestions, and
     questions are always welcome.


    John W. Small
    PSW / Power SoftWare
    P.O. Box 10072
    McLean, VA 22102 8072 USA

    Voice: [phone]
    CIS: 73757,2233


     Happy Authoring!

        John